demos: introduce DevModule + rename bin/app.php to bin/be.php - #19

demos/user-registration/src/Becoming/DevBecoming.php (2)

30-46: Exception raised inside finally would mask the original Becoming failure.

If writing the log throws (e.g., disk full, permissions, json_encode returning false with JSON_THROW_ON_ERROR-like semantics indirectly via a later call), that exception replaces any exception propagating from ($this->becoming)($input), hiding the real pipeline failure from the developer running the demo. For a dev-only tool this is acceptable, but wrapping the persistence in its own try/catch (logging to stderr instead of throwing) would keep the observed failure signal intact.

♻️ Optional hardening

         try {
             return ($this->becoming)($input);
         } finally {
-            $dir = dirname(__DIR__, 2) . '/var/log';
-            if (! is_dir($dir)) {
-                mkdir($dir, 0755, true);
-            }
-
-            file_put_contents(
-                $dir . '/user-registration.json',
-                json_encode($this->logger->flush(), JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE),
-            );
+            try {
+                $dir = dirname(__DIR__, 2) . '/var/log';
+                if (! is_dir($dir)) {
+                    mkdir($dir, 0755, true);
+                }
+
+                $json = json_encode(
+                    $this->logger->flush(),
+                    JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE,
+                );
+                if ($json !== false) {
+                    file_put_contents($dir . '/user-registration.json', $json);
+                }
+            } catch (\Throwable $e) {
+                fwrite(STDERR, "DevBecoming log write failed: {$e->getMessage()}\n");
+            }
         }

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@demos/user-registration/src/Becoming/DevBecoming.php` around lines 30 - 46,
The finally block in DevBecoming::__invoke currently writes logs and can throw,
which would mask exceptions from ($this->becoming)($input); wrap the entire
persistence sequence (the dirname/ mkdir check, json_encode of
$this->logger->flush(), and file_put_contents) in its own try/catch inside the
finally so any errors are caught and do not propagate; on catch write a concise
error to STDERR (e.g., via fwrite(STDERR, ...)) and do not rethrow; additionally
validate json_encode succeeded (or use JSON_THROW_ON_ERROR inside that try)
before calling file_put_contents to avoid silent false results from
$this->logger->flush().

---

22-47: Heads-up: near-identical DevBecoming will land in each demo.

This class is structurally the same across the four demos, differing only in the JSON filename (user-registration.json, hello-world.json, etc.). That’s consistent with the PR’s “per-demo DevModule” philosophy, and the filename-by-demo is the only real variation — so a shared base class probably isn’t worth it. Flagging only so future maintainers know any bug fix here (e.g., the finally concern above) needs to be replicated in the other three DevBecoming files.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@demos/user-registration/src/Becoming/DevBecoming.php` around lines 22 - 47,
DevBecoming's __invoke finally block is duplicated across demos with only the
output filename differing (e.g., user-registration.json vs hello-world.json);
when you fix the finally behavior (e.g., ensure logger->flush() errors are
handled, directory creation permissions, or atomic file write), apply the same
change to the other DevBecoming classes so all demos stay consistent—locate the
DevBecoming class and its __invoke method and update the file write logic
(logger->flush(), dirname(...)/var/log creation, and file_put_contents call) and
replicate the identical fix to the other three DevBecoming files, preserving
each demo's distinct JSON filename.

demos/medical-triage/bin/be.php (1)

22-27: Consider asserting the final type for parity with other demos.

The sibling entrypoints (hello-world, user-registration, order-processing) all do assert($final instanceof <FinalClass>) before using the result. This script only prints $final::class, so if the pipeline ever returns an unexpected object the demo silently accepts it. Adding a matching assert keeps the demos consistent and documents the expected outcome.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@demos/medical-triage/bin/be.php` around lines 22 - 27, Add an instanceof
assertion to verify the pipeline output ($final) matches the expected final
class before using it: locate the code that calls $becoming(new
PatientInput(...)) and immediately after the result is produced (before or after
the printf) add an assertion like assert($final instanceof <ExpectedFinalClass>)
— replace <ExpectedFinalClass> with the actual final type returned by the triage
pipeline (e.g., TriageResult) to match the other demos' pattern and document the
expected outcome.

demos/user-registration/bin/be.php (1)

33-33: Relative vendor/bin/stree path couples script to CWD.

passthru('vendor/bin/stree ' . ...) only resolves when invoked from the demo directory (as documented in the PR test plan). Running php demos/user-registration/bin/be.php from the repo root will fail to locate stree even though the script otherwise works via dirname(__DIR__) for autoload. Consider resolving the binary path relative to the script, mirroring how vendor/autoload.php is resolved.

♻️ Proposed fix

-passthru('vendor/bin/stree ' . escapeshellarg(dirname(__DIR__) . '/var/log/user-registration.json'));
+passthru(
+    escapeshellarg(dirname(__DIR__) . '/vendor/bin/stree') . ' '
+    . escapeshellarg(dirname(__DIR__) . '/var/log/user-registration.json'),
+);

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@demos/user-registration/bin/be.php` at line 33, The passthru call uses a
relative 'vendor/bin/stree' which breaks when the script is run from a different
CWD; change the command to build the binary path relative to the script
directory (use dirname(__DIR__, 3) to reach the repo root from
demos/user-registration/bin), e.g. compute the full path to vendor/bin/stree via
dirname(__DIR__, 3) . '/vendor/bin/stree', wrap it with escapeshellarg as
before, and use that value in the passthru call (keep the existing passthru,
escapeshellarg and dirname usage but resolve vendor/bin/stree relative to the
script).

demos/medical-triage/src/Becoming/DevBecoming.php (1)

22-47: Consider extracting shared DevBecoming logic to reduce per-demo duplication.

This class is nearly identical across hello-world, medical-triage, order-processing, and user-registration — only the output filename differs. Since each demo has its own src/ tree and composer.json, full deduplication may be out of scope, but you could at least parameterize the log filename (e.g., pass it via a #[Named] string binding in DevModule) so the class bodies become trivially mergeable later, or ship a single shared helper. Optional — purely a maintainability nit for dev-only code.

Also, two minor robustness notes for the finally block:

• json_encode(...) can return false (e.g., on malformed UTF-8 or a circular structure thrown from flush()); file_put_contents will then silently write an empty file, masking the real problem. Adding JSON_THROW_ON_ERROR would surface it.
• mkdir(...) return value is ignored; if creation fails due to a race or permissions, the subsequent write fails silently.

♻️ Suggested tightening

-            $dir = dirname(__DIR__, 2) . '/var/log';
-            if (! is_dir($dir)) {
-                mkdir($dir, 0755, true);
-            }
-
-            file_put_contents(
-                $dir . '/medical-triage.json',
-                json_encode($this->logger->flush(), JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE),
-            );
+            $dir = dirname(__DIR__, 2) . '/var/log';
+            if (! is_dir($dir) && ! mkdir($dir, 0755, true) && ! is_dir($dir)) {
+                return;
+            }
+
+            file_put_contents(
+                $dir . '/medical-triage.json',
+                json_encode(
+                    $this->logger->flush(),
+                    JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR,
+                ),
+            );

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@demos/medical-triage/src/Becoming/DevBecoming.php` around lines 22 - 47,
DevBecoming's finally block should be made robust and the filename
parameterized: change DevBecoming to accept a filename (e.g., via the
constructor/#[Named] binding) instead of hardcoding 'medical-triage.json', and
update __invoke to use that injected filename; in the finally block, call
json_encode/flush with JSON_THROW_ON_ERROR to surface encoding errors (catching
and logging if needed), ensure mkdir succeeded (or re-check is_dir and log/throw
if creation failed) before writing, and verify file_put_contents returned a
non-false result (log/throw on failure) after calling $this->logger->flush() so
write errors aren’t silently ignored.

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes